Switch to mkdocs material theme for documentation by browniebroke · Pull Request #9849 · encode/django-rest-framework

browniebroke · 2025-12-15T19:27:23Z

Description

Explore replacing our theme by mkdocs-material.

Light theme:

Dark theme:

Some things I'm not happy about:

I think the colors for the dark theme aren't quite there yet (especially the contrast of the links).
~~Syntax highlighting for code snippets is lost unless we switch to code fences (no idea how it works now)~~ figured it out and ported the exiting solution to limit the diff
This theme has a lot of features, there might be more to enable

Syntax highlighting

Existing solution relies on prettify-1.0.js which is apprently coming from https://github.com/googlearchive/code-prettify

JS is added to the main HTML document
There is a piece in theme.js which adds the class prettyprint to all <pre> tags
The main HTML doc run prettyPrint() on load (via the onload HTML attribute). This function finds all elements with the class above and add syntax highliting to them

I've replicated this in mkdocs-material, however there is some client side navigation, which means we need to listen to another event than DOM content loaded. This is explained in their docs

…mkdocs-material # Conflicts: # docs/theme/stylesheets/extra.css # mkdocs.yml

# Conflicts: # requirements/requirements-documentation.txt

browniebroke · 2026-02-11T22:58:12Z

Configured a dummy RTD project to have a live deployment of the PR: https://browniebroke-drf--2.org.readthedocs.build/en/2/

Natgho · 2026-02-25T08:34:17Z

before:

after:

First of all, I should mention that I am not a FE developer or UI/UX designer, and colors are entirely subjective :)

But for a more fluid look, wouldn't it be more stylish if the burgundy at the top of the interface and the colors of the squares were the same?

browniebroke · 2026-02-25T08:43:20Z

But for a more fluid look, wouldn't it be more stylish if the burgundy at the top of the interface and the colors of the squares were the same?

At first glance, that seems like a lot of "red" to me 😊 Making the square burgundy almost feels like they are outlines for an error/danger callout...

That being said I think you have a point that the white ones don't look great either

Natgho · 2026-02-25T08:48:07Z

That being said I think you have a point that the white ones don't look great either

UI design, color selections... It can easily become a nightmare :)
What about completely same with background color ?

browniebroke · 2026-02-25T08:51:38Z

Updated:

browniebroke · 2026-02-27T13:53:31Z

I think this pretty much ready for merge now. Unless there is any objections or blocking issue found, I'm planning to merge it in a few days.

Copilot

Pull request overview

This PR migrates the project’s documentation site from the legacy custom MkDocs theme to MkDocs Material, carrying forward custom branding and restoring syntax highlighting behavior.

Changes:

Switch MkDocs theme to material and enable Material navigation/code/search features.
Add a new docs/theme/ override theme with custom CSS, images, and JS to re-enable prettify-based highlighting.
Add Read the Docs configuration and update the documentation homepage markup/assets.

Reviewed changes

Copilot reviewed 20 out of 31 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
`pyproject.toml`	Adds `mkdocs-material[imaging]` to the `docs` dependency group.
`mkdocs.yml`	Switches to Material theme, enables features, and updates extensions/assets.
`docs_theme/nav.html`	Removes legacy theme navigation template.
`docs_theme/main.html`	Removes legacy theme base template and old JS/CSS wiring.
`docs_theme/js/theme.js`	Removes legacy theme JS (incl. prettyprint class injection).
`docs_theme/js/copy-button.js`	Removes legacy code-copy button JS (Material provides copy feature).
`docs_theme/js/bootstrap-2.1.1-min.js`	Removes vendored Bootstrap JS from the legacy theme.
`docs_theme/css/default.css`	Removes legacy theme CSS.
`docs_theme/css/copy-button.css`	Removes legacy copy-button CSS.
`docs_theme/css/bootstrap-responsive.css`	Removes legacy responsive Bootstrap CSS.
`docs_theme/404.html`	Removes legacy theme 404 template.
`docs_theme/img/glyphicons-halflings.png`	Removes legacy theme asset.
`docs_theme/img/glyphicons-halflings-white.png`	Removes legacy theme asset.
`docs/theme/main.html`	Adds Material template override to run prettify on instant navigation.
`docs/theme/stylesheets/extra.css`	Adds Material theme customizations (colors, badges layout, blockquotes, background).
`docs/theme/stylesheets/prettify.css`	Adds dark-scheme prettify styles.
`docs/theme/js/prettify-1.0.js`	Vendors prettify JS for syntax highlighting.
`docs/theme/img/logo.png`	Adds theme logo for header/branding.
`docs/theme/img/grid.png`	Adds background image used by custom CSS.
`docs/theme/img/favicon.ico`	Adds theme favicon.
`docs/theme/src/drf-logos.fig`	Adds logo source asset via Git LFS pointer.
`docs/theme/src/README.md`	Documents the logo source file location.
`docs/index.md`	Updates homepage markup, uses Material light/dark logo switching, and converts code blocks to fenced code.
`.readthedocs.yaml`	Adds RTD build config to build MkDocs using the `docs` dependency group.
`.gitignore`	Stops ignoring all dotfiles and adds common coverage/cache ignores.
`.gitattributes`	Configures Git LFS tracking for the `.fig` source asset.

Comments suppressed due to low confidence (1)

docs/theme/stylesheets/prettify.css:16

This file uses CSS nesting ([data-md-color-scheme="slate"] { .com { ... } }), which is not supported in all browsers unless you have a build step that transpiles it. Also, there’s an extra semicolon in .str, .atv { color: #e37e8e;; }. Consider flattening the selectors (e.g., prefix each rule with [data-md-color-scheme="slate"]) and fixing the stray semicolon to keep the stylesheet valid and broadly compatible.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-02-28T05:12:28Z

mkdocs.yml

+    - content.tabs.link
+    - content.code.annotate
+    - content.code.copy
+    - navigation.tabs
+    - navigation.tabs.sticky
+    - navigation.instant
+    - navigation.instant.prefetch
+    - navigation.instant.progress
+    - navigation.path
+    - navigation.sections
+    - navigation.top
+    - navigation.tracking
+    - search.suggest
+    - toc.follow
+    - toc.integrate


theme.features is not valid YAML here: the list entries are aligned with features: instead of being indented under it. As written, the - content.* and - navigation.* items become sibling keys (or cause a parse error), so MkDocs will fail to load the config. Indent the feature list items under features:.

Suggested change

- content.tabs.link

- content.code.annotate

- content.code.copy

- navigation.tabs

- navigation.tabs.sticky

- navigation.instant

- navigation.instant.prefetch

- navigation.instant.progress

- navigation.path

- navigation.sections

- navigation.top

- navigation.tracking

- search.suggest

- toc.follow

- toc.integrate

- content.tabs.link

- content.code.annotate

- content.code.copy

- navigation.tabs

- navigation.tabs.sticky

- navigation.instant

- navigation.instant.prefetch

- navigation.instant.progress

- navigation.path

- navigation.sections

- navigation.top

- navigation.tracking

- search.suggest

- toc.follow

- toc.integrate

Copilot · 2026-02-28T05:12:29Z

docs/theme/stylesheets/extra.css

+.badges {
+  display: flex;
+  flex-direction: row-reverse;
+  align-content: end;


In .badges, align-content: end; won’t have any effect because the container doesn’t wrap (flex-wrap defaults to nowrap). If the intent is to vertically align the badges within the row, use align-items (and likely flex-end) instead, or explicitly enable wrapping if you meant align-content.

Suggested change

align-content: end;

align-items: flex-end;

browniebroke added 16 commits December 12, 2025 16:24

Switch to mkdocs material theme

2c7c1b3

Add logo

319dbcd

Style badges on homepage

e277940

Basic dark theme

68203cb

Enable a few theme features

a8af6a7

Customise large logo for dark theme

0b98599

CSS tweaks

cd2ee60

Add background grid back

fbe8731

Switch to mkdocs material theme

3f5399b

Add logo

38f5513

Style badges on homepage

6d5dd9c

Basic dark theme

5a44bec

Add syntax highlighting to code snippets

2ea8cb1

Merge remote-tracking branch 'origin/feat/mkdocs-material' into feat/…

05cabcd

…mkdocs-material # Conflicts: # docs/theme/stylesheets/extra.css # mkdocs.yml

Convert homepage snippets to code fences

9125483

Update homepage logos

2087222

auvipy self-requested a review December 15, 2025 19:38

browniebroke added 5 commits February 10, 2026 08:13

Merge branch 'main' into feat/mkdocs-material

4efe942

# Conflicts: # requirements/requirements-documentation.txt

Move mkdocs-material to pyproject.toml docs group

3091af7

Keep existing syntax highlighting

35be8fb

Remove old docs_theme folder

692196a

Tweak syntax highlighting colors on dark theme

4b6053b

browniebroke marked this pull request as ready for review February 10, 2026 09:13

browniebroke mentioned this pull request Feb 11, 2026

Switch doc theme to mkdocs-material browniebroke/django-rest-framework#2

Draft

browniebroke added 3 commits February 11, 2026 21:06

Add readthedocs config file

abc1951

Fix end of file empty lines

fc2ca65

Upgrade pip during install

339a04f

Merge branch 'main' into feat/mkdocs-material

2563b83

browniebroke added this to the 3.17 milestone Feb 19, 2026

Merge branch 'main' into feat/mkdocs-material

6a06cde

Merge branch 'main' into feat/mkdocs-material

11293f0

Remove custom styling for .prettyprint

5a74bb2

browniebroke added 5 commits February 26, 2026 13:54

Remove .prettyprint border entirely

77d578c

Make tabs sticky in navbar

fa6039a

Merge page ToC with navigation

ffff7ee

Tweak colors for more accessible contrast

9be5124

Add Figma file for the logos

1f7feaa

browniebroke force-pushed the feat/mkdocs-material branch from 9d84ed0 to 1f7feaa Compare February 26, 2026 19:44

Merge branch 'main' into feat/mkdocs-material

095e6c4

auvipy requested a review from Copilot February 28, 2026 05:07

Copilot started reviewing on behalf of auvipy February 28, 2026 05:07 View session

Copilot AI reviewed Feb 28, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Switch to mkdocs material theme for documentation#9849

Switch to mkdocs material theme for documentation#9849
browniebroke wants to merge 34 commits intoencode:mainfrom
browniebroke:feat/mkdocs-material

browniebroke commented Dec 15, 2025 •

edited

Loading

Uh oh!

browniebroke commented Feb 11, 2026

Uh oh!

Natgho commented Feb 25, 2026

Uh oh!

browniebroke commented Feb 25, 2026 •

edited

Loading

Uh oh!

Natgho commented Feb 25, 2026

Uh oh!

browniebroke commented Feb 25, 2026

Uh oh!

browniebroke commented Feb 27, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Feb 28, 2026

Uh oh!

Copilot AI Feb 28, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Uh oh!

Conversation

browniebroke commented Dec 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Uh oh!

browniebroke commented Feb 11, 2026

Uh oh!

Natgho commented Feb 25, 2026

Uh oh!

browniebroke commented Feb 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Natgho commented Feb 25, 2026

Uh oh!

browniebroke commented Feb 25, 2026

Uh oh!

browniebroke commented Feb 27, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Feb 28, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 28, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

browniebroke commented Dec 15, 2025 •

edited

Loading

browniebroke commented Feb 25, 2026 •

edited

Loading